home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / 2924.ZIP / DMLXREF.ARC / NUM.DOC < prev    next >
Encoding:
Text File  |  1988-12-28  |  17.3 KB  |  609 lines
  1. .KF:Num.toc
  2. .R:E
  3. .W:96
  4. .H:...DML NUM UNIT Version 1.00...
  5. .H:...$$Day Mon D, YEAR$$  $$Z:MI A.M.$$     Page $$$...
  6. .H:
  7. .F:
  8. .F:... Copyright (c) 1989, by DML Software Inc. ...
  9. .X:8
  10.  
  11.  
  12. .K:NUMERIC ROUTINES - CHANGES HIGHLIGHTS (VERSION 1.00)
  13. NUMERIC ROUTINES - CHANGES HIGHLIGHTS  (VERSION 1.00)
  14.  
  15. 1/1/89 Initial Release
  16.  
  17.   
  18.  
  19. .K:1) GENERAL NUMERIC FORMATTING AND CONVERSION
  20. 1) GENERAL NUMERIC FORMATTING AND CONVERSION
  21.  
  22.   NAME
  23. .K:B2S - Boolean to String Conversion.
  24.      B2S - Boolean to String Conversion.
  25.  
  26.   SYNOPSIS
  27.      FUNCTION B2S (Flag : BOOLEAN) : STRING;
  28.  
  29.      WRITELN (B2S (123 = 123));
  30.  
  31.   DESCRIPTION
  32.      Returns a string of TRUE or FALSE depending on th value of the Boolean 
  33.      parameter.
  34.  
  35.   SEE ALSO
  36.  
  37.   DEPENDS ON
  38.  
  39.   DIAGNOSTICS
  40.  
  41.   KNOWN RESTRICTIONS
  42.  
  43.   PARTIALLY OBSOLETED BY
  44.  
  45.   UPDATE HISTORY
  46.  
  47.   
  48.  
  49.   NAME
  50. .K:I2S - Integer to String Conversion
  51.      I2S - Integer to String Conversion
  52. .K:W2S - Word to String Conversion
  53.      I2S - Word to String Conversion
  54. .K:L2S - LongInt to String Conversion
  55.      L2S - LongInt to String Conversion
  56.  
  57.   SYNOPSIS
  58.      FUNCTION I2S (Num : INTEGER; Mask : STRING) : STRING;
  59.      FUNCTION W2S (Num : WORD;    Mask : STRING) : STRING;
  60.      FUNCTION L2S (Num : LONGINT; Mask : STRING) : STRING;
  61.  
  62.      WRITELN ('The meaning of everything: ', I2S (42, '##'));
  63.      WRITELN ('Bit fields in hex: ', W2S (AX, 'HHHH'));
  64.      WRITELN ('Big number: ', L2S (-12345678, '-###,###,##@'));
  65.  
  66.   DESCRIPTION
  67.      Returns a string of the number passed.  The following characters can
  68.      be used in the mask string.  Remember that the case of the character
  69.      is important and that 'H' <> 'h'.
  70.  
  71.   sp   - The space character will be output in this position.
  72.  
  73.          # ###.## : 1234.56 = '1 234.56', 50.00 = '   50   ', 0 = '        '
  74.  
  75.   #    - Digit base 10, leading and trailing zero digits are blank.
  76.  
  77.          # ###.## : 1234.56 = '1 234.56', 50.00 = '   50   ', 0 = '        '
  78.  
  79.   H    - Digit base 16, leading and trailing zero digits are blank. (Int only)
  80.  
  81.          HHHH     : 43981   = 'ABCD'    , 50    = '  32'    , 0 = '    '
  82.  
  83.   B    - NOT IMPLEMENTED  (for binary)
  84.  
  85.          BBBB     : 10      = '1010'    ,  2    = '  10'   , 0 - '    '
  86.  
  87.   @    - Digit, from position to decimal point, zero digits are '0'.
  88.  
  89.          # #@#.#@ : 1234.56 = '1 234.56', 50.00 = '   50.00', 0 = '   00.00'
  90.  
  91.   *    - Digit, from position to decimal point, zero digits are '*'.
  92.  
  93.          # #*#.#* : 1234.56 = '1 234.56', 50.00 = '   50***', 0 = '   **.**'
  94.  
  95.   $    - Space before number is a dollar sign. NOT a digit position.
  96.          Can also follow the number.
  97.  
  98.          $####.## : 1234.56 = '$1234.56', 50.00 = '  $50   ', 0 = '        '
  99. 
  100.  
  101.   -    - If negative, space before number is '-', if positive then ' '.
  102.          Can also follow the number.
  103.  
  104.          -####.## : 1234.56 = ' 1234.56', -5.00 = '   -5   ', 0 = '        '
  105.  
  106.   +    - If negative, space before number is '-', if positive then '+'.
  107.          Can also follow the number.  The + will not be displayed if no
  108.          digits in the number are displayed.
  109.  
  110.          +####.## : 1234.56 = '+1234.56', -5.00 = '   -5   ', 0 = '        '
  111.  
  112.   ( )  - If negative, parenthesis around number, else blanks around.
  113.  
  114.          (####.#) : 1234.5  = ' 1234.5 ', -5.00 = '   (5  )', 0 = '        '
  115.  
  116.  
  117.   ,    - Thousands separator (comma).
  118.   .    - Decimal   separator (period).
  119.  
  120.          #,###.## : 1234.56 = '1,234.56', 50.00 = '   50   ', 0 = '        '
  121.  
  122.   SEE ALSO
  123.      S2I - String to Integer
  124.  
  125.   DEPENDS ON
  126.  
  127.   DIAGNOSTICS
  128.      The mask must have the proper characters present or the resulting
  129.      string will be invalid.  If the Mask is too small to hold the number
  130.      all stars '*' will be returned. If the number is negative and a sign
  131.      character has not been used then the result will also be all stars.
  132.      If the mask is inconsistant, and cannot be decoded, then all questions
  133.      '?' will be returned.
  134.  
  135.   KNOWN RESTRICTIONS
  136.      THERE IS CURRENTLY NO CHECKING DONE OF THE MASK.  This means that a
  137.      mask of $#$#$# is perfectly valid and will return a dollar sign
  138.      between every digit.
  139.  
  140.      Will float either the sign (-,+), or the dollar sign (+), but will only 
  141.      float both if the minus sign is used: (-$ or $-)
  142.  
  143.   PARTIALLY OBSOLETED BY
  144.  
  145.   UPDATE HISTORY
  146.  
  147.   
  148.  
  149.   NAME
  150. .K:R2S - Real to String Conversion
  151.      R2S - Real to String Conversion
  152. .K:D2S - Double to String Conversion
  153.      D2S - Double to String Conversion
  154.  
  155.   SYNOPSIS
  156.      FUNCTION R2S (Num : REAL;   Mask : STRING) : STRING;
  157.      FUNCTION D2S (Num : DOUBLE; Mask : STRING) : STRING;
  158.  
  159.      WRITELN ('Total Due: ', R2S (4356.50, '$(#####.##)');
  160.      WRITELN ('Miles to Neptune: ', D2S (123456789.4356, '###,###,##,##@.##)');
  161.  
  162.   DESCRIPTION
  163.      Returns a string of the real number passed.  The number of decimal
  164.      places is calculated from the mask.  Therefore, the mask "##.###"
  165.      specifies a field length of 6 and 3 decimal places.  The decimal
  166.      places are rounded, but a .5 is rounded DOWN.  This is a function of
  167.      the Turbo routine STR, and if you want to round up, you'll have to add
  168.      some small fraction to your number.  Also remember that if you specify
  169.      more than 24 decimal positions the result will be in scientific
  170.      notation which is curently not supported very well.  See I2S for more
  171.      info on the mask parameter, and the characters within the mask.
  172.  
  173.   SEE ALSO
  174.      I2S - Integer to String, S2R - String to Real
  175.  
  176.   DEPENDS ON
  177.  
  178.   DIAGNOSTICS
  179.      The mask must have the proper characters present or the resulting
  180.      string will be invalid.  If the Mask is too small to hold the number
  181.      all stars '*' will be returned. If the number is negative and a sign
  182.      character has not been used then the result will also be all stars. If
  183.      the mask is inconsistant, and cannot be decoded, then all questions
  184.      '?' will be returned.
  185.  
  186.   KNOWN RESTRICTIONS
  187.      THERE IS CURRENTLY NO CHECKING DONE OF THE MASK.  This means that a
  188.      mask of $#$#$# is perfectly valid and will return a dollar sign
  189.      between every digit.
  190.  
  191.      To print a phone number just make the 10 digit number negative and use
  192.      the following mask '(###) ###-####'
  193.  
  194.   PARTIALLY OBSOLETED BY
  195.  
  196.   UPDATE HISTORY
  197.  
  198.   
  199.  
  200.   NAME
  201. .K:S2R - String to Real Conversion
  202.      S2R - String to Real Conversion
  203. .K:S2D - String to Double Conversion
  204.      S2D - String to Double Conversion
  205.  
  206.   SYNOPSIS
  207.      FUNCTION S2R (Source : STRING) : REAL;
  208.      FUNCTION S2D (Source : STRING) : DOUBLE;
  209.  
  210.      VAR
  211.        Number : REAL:
  212.  
  213.      BEGIN
  214.        Number := S2R ('$( 1,435.43)');
  215.        WRITELN(S2D('12345.6789');
  216.      END;
  217.  
  218.   DESCRIPTION
  219.      Converts a string into a real number.  All characters that are not in
  220.      the set ['0'..'9', '.'] are simply ignored.  However, parenthesis and
  221.      minus signs are scanned for (sic) to determine the sign of the number.
  222.      All real numbers are assumed to be base 10.
  223.  
  224.   SEE ALSO
  225.      R2S - Real to String
  226.      StrNumTest
  227.  
  228.   DEPENDS ON
  229.  
  230.   DIAGNOSTICS
  231.      If the string contains no valid digits then the value zero will be 
  232.      returned; test the string first with StrNumTest.  If the string contains 
  233.      more digits than will fit into a real number then a run-time error will 
  234.      occur halting the program. 
  235.  
  236.      If a conversion error can't be trapped before the string is actually 
  237.      converted with the Turbo VAL proc, the string and the character 
  238.      position of the failed conversion will be displayed, and zero will be 
  239.      returned.
  240.  
  241.   KNOWN RESTRICTIONS
  242.  
  243.   PARTIALLY OBSOLETED BY 
  244.  
  245.   UPDATE HISTORY
  246.  
  247.   
  248.  
  249.   NAME
  250. .K:StrNumTest - Test Numeric String.
  251.      StrNumTest - Test Numeric String.
  252.  
  253.   SYNOPSIS
  254.      FUNCTION StrNumTest (Fld : STRING) : StrNumType;
  255.  
  256.      VAR
  257.        StrNumOrd : StrNumType
  258.        StrNum    : STRING;
  259.  
  260.      BEGIN
  261.        StrNumOrd := StrNumTest(StrNum);
  262.        CASE StrNumOrd OF
  263.          StrNonNumeric : WRITELN('String has no numeric characters');
  264.          StrZero       : WRITELN('String has numeric value of zero');
  265.          StrNonZero    : WRITELN('String has numeric value of non zero');
  266.          END;
  267.        WRITELN(S2L(StrNum));
  268.      END;
  269.  
  270.   DESCRIPTION
  271.      Returns an ordinal value of NonNumeric, Zero, or NonZero for the string 
  272.      parameter supplied.  If no numeric charcters 0..9 are found, then 
  273.      NonNumeric is returned.  Otherwise If the string 'value' is zero, then 
  274.      Zero is returned.  Otherwise NonZero is returned.  Since S2x returns zero 
  275.      for nonnumerics and overflow, as well as legitimate zero, invoking this 
  276.      function first is advised.
  277.  
  278.   SEE ALSO
  279.      S2I
  280.  
  281.   DEPENDS ON
  282.  
  283.   DIAGNOSTICS
  284.  
  285.   KNOWN RESTRICTIONS
  286.  
  287.   PARTIALLY OBSOLETED BY
  288.  
  289.   UPDATE HISTORY
  290.  
  291.   
  292.  
  293.   NAME
  294. .K:S2I - String to Integer Conversion
  295.      S2I - String to Integer Conversion
  296. .K:S2W - String to WordConversion
  297.      S2W - String to Word Conversion
  298. .K:S2L - String to LongInt Conversion
  299.      S2L - String to LongInt Conversion
  300.  
  301.   SYNOPSIS
  302.      FUNCTION S2I (Source : STRING) : INTEGER;
  303.      FUNCTION S2W (Source : STRING) : WORD;
  304.      FUNCTION S2L (Source : STRING) : LONGINT;
  305.  
  306.      VAR
  307.        HexNumber : INTEGER;
  308.  
  309.      BEGIN
  310.        WRITELN(S2I('32,767'));
  311.        HexNumber := S2W ('H4BAD');
  312.        WRITELN(S2L('2,123,456,890'));
  313.      END;
  314.  
  315.   DESCRIPTION
  316.      Converts a string into an integer value.  If the string has the letter
  317.      H before or after the number, the number is assumed to be in
  318.      hexidecimal format and is coverted as such.  If the string has the
  319.      letter B before or after the number it is assumed to be a binary
  320.      number and converted as such.  All characters which cannot be digits
  321.      are removed from the string. For example, all commas are removed.  In
  322.      a binary number any character which is not a '0' or '1' is removed so
  323.      that the number 1231 will have the binary string value '11' which
  324.      equals 3.  The conversion will also stop after the first '.' found, i.e 
  325.      '123.45' will convert to 123.   
  326.  
  327.    SEE ALSO
  328.      I2S - Integer to String
  329.      StrNumTest 
  330.  
  331.   DEPENDS ON
  332.  
  333.   DIAGNOSTICS
  334.      If no numeric characters are found, or the numeric value overflows the 
  335.      result type, zero will be returned; test the string first with 
  336.      StrNumTest.  
  337.   
  338.      If a conversion error can't be trapped before the string is actually 
  339.      converted with the Turbo VAL proc, the string and the character 
  340.      position of the failed conversion will be displayed, and zero will be 
  341.      returned.
  342.  
  343.   KNOWN RESTRICTIONS
  344.  
  345.   PARTIALLY OBSOLETED BY 
  346.  
  347.   UPDATE HISTORY
  348.  
  349.   
  350.  
  351.  
  352. .K:2) DATE AND TIME FORMATTING AND CONVERSION
  353. 2) DATE AND TIME FORMATTING AND CONVERSION
  354.  
  355.   NAME
  356. .K:Numth - Returns a string with the number followed by 'th'
  357.      Numth - Returns a string with the number followed by 'th'
  358.  
  359.   SYNOPSIS
  360.      FUNCTION NumTh (Num : INTEGER) : MaxStr;
  361.  
  362.      WRITELN ('Today is the ', Numth (5), ' day of the week.');
  363.  
  364.   DESCRIPTION
  365.      Converts a decimal integer into a string with a following 'th' as in
  366.      4th, 3rd, 2nd and 1st.  This routine is really for use with the date
  367.      conversions, but it might be useful elsewhere.
  368.  
  369.   SEE ALSO
  370.      Date2S - Date to String
  371.  
  372.   DEPENDS ON
  373.      I2S
  374.  
  375.   DIAGNOSTICS
  376.  
  377.   KNOWN RESTRICTIONS
  378.  
  379.   PARTIALLY OBSOLETED BY 
  380.  
  381.   UPDATE HISTORY
  382.  
  383.   
  384.  
  385.   NAME
  386. .K:Date2R - Date to Real.
  387.      Date2R - Date to Real.
  388.  
  389.   SYNOPSIS
  390.      PROCEDURE Date2R (VAR JulSec : REAL; DateTime : T_DateTime);
  391.  
  392.      VAR
  393.        NumberSeconds : REAL;
  394.  
  395.      BEGIN
  396.        WITH DateTime DO BEGIN
  397.          Month  := 6;
  398.          Day    := 13;
  399.          Year   := 1986;
  400.          Hour   := 00;
  401.          Minute := 23;
  402.          Second := 44;
  403.          END;
  404.  
  405.        Date2R (NumberSeconds, DateTime);
  406.        WRITELN ('Seconds from 12/31/1840 midnight: ', NumberSeconds);
  407.      END;
  408.  
  409.   DESCRIPTION
  410.      Date to Real returns a real number which is the number of "Julian
  411.      seconds" from some known point.  The variable DateTime contains the
  412.      exact time in month day year hours minutes and seconds.  All these are
  413.      multiplied (taking into account leap years properly) to arrive at the
  414.      number of seconds.
  415.  
  416.   SEE ALSO
  417.      R2Date - Real to Date, Date2S - Date to String, GetDOSDateAndTime
  418.  
  419.   DEPENDS ON
  420.  
  421.   DIAGNOSTICS
  422.  
  423.   KNOWN RESTRICTIONS
  424.      No testing is done for negative values.
  425.      Leap years AND Leap centuries ARE correctly handled.
  426.  
  427.   PARTIALLY OBSOLETED BY 
  428.  
  429.   UPDATE HISTORY
  430.  
  431.   
  432.  
  433.   NAME
  434. .K:R2Date - Real to DateTime
  435.      R2Date - Real to DateTime
  436.  
  437.   SYNOPSIS
  438.      PROCEDURE R2Date (JulSec : REAL; VAR DateTime : T_DateTime);
  439.  
  440.      VAR
  441.        DT : T_DateTime;
  442.  
  443.      BEGIN
  444.        R2Date (8904534450.0, DT);
  445.        WRITELN ('Today is: ', Date2S (DT, 'WWWW'));
  446.      END;
  447.  
  448.   DESCRIPTION
  449.      Converts the number of julian seconds to the DateTime record while
  450.      properly converting leap years and leap centuries.
  451.  
  452.   SEE ALSO
  453.       Date2S - Date to String, Date2R - Date to Real
  454.  
  455.   DEPENDS ON
  456.  
  457.   DIAGNOSTICS
  458.  
  459.   KNOWN RESTRICTIONS
  460.  
  461.   PARTIALLY OBSOLETED BY 
  462.  
  463.   UPDATE HISTORY
  464.  
  465.   
  466.  
  467.   NAME
  468. .K:Date2S - Date to String.
  469.      Date2S - Date to String.
  470.  
  471.   SYNOPSIS
  472.      FUNCTION Date2S (DateTime : T_DateTime; Mask : MaxStr) : MaxStr;
  473.  
  474.      WRITELN ('Today is: ', Date2S(DateTime, 'WWW MM/DD/YY hh:mm:ss pm'));
  475.  
  476.   DESCRIPTION
  477.      Date to string returns a string with the correctly formatted date and
  478.      time.  The mask can consist of any of the following characters:
  479.  
  480.      (The case of the below is significant!  e.g. 'W' <> 'w')
  481.  
  482.        WWW   - Three letter weekday name
  483.        WWWW  - Full weekday name, variable length
  484.        MM    - Numeric month
  485.        MMM   - Three letter month name
  486.        MMMM  - Full month name, variable length
  487.        DD    - Numeric day of month, with leading zeros
  488.        DDDD  - Day of month, leading spaces, followed by st, nd, rd or th
  489.        YY    - Year in century, 20 could mean 1820, 1920, 2020, etc
  490.        YYYY  - Full year
  491.        hh    - Hours either in 24 or 12 format
  492.        mm    - Minutes
  493.        ss    - Seconds
  494.        a     - Am indicator - changes to 12 hour format am and pm shown
  495.        p     - Am indicator - changes to 12 hour format only pm is shown
  496.        E     - European date expected, e.g. EYY/MM/DD
  497.  
  498.   SEE ALSO
  499.      Date2R - Date to Real, R2Date - Real to Date, GetDOSDateAndTime
  500.  
  501.   DEPENDS ON
  502.  
  503.   DIAGNOSTICS
  504.      If the mask passed is incorrect, parts of the mask will simply be
  505.      returned unfilled.  If any the integer fields in the DateTime record
  506.      are larger than 99 or less than 0 the mask may have stars in those
  507.      fields indicating overflow.
  508.  
  509.   KNOWN RESTRICTIONS
  510.      No parsing is performed on the mask.  The mask will not be filled
  511.      properly unless the mask characters are in the correct order.
  512.      Weekdays, Month, Day, Year followed by hour minute and second.  Any of
  513.      them may be left out, but if they are out of order, it won't work.
  514.  
  515.   PARTIALLY OBSOLETED BY 
  516.      UnPackTime
  517.  
  518.   UPDATE HISTORY
  519.  
  520.   
  521.  
  522.   NAME
  523. .K:GetDOSDateAndTime - Returns both the number of seconds from 12/31/1840
  524.      GetDOSDateAndTime - Returns both the number of seconds from 12/31/1840
  525.                          midnight, and the DateTime record containing the
  526.                          date, time and elapsed times from the DOS system
  527.                          clock.
  528.  
  529.   SYNOPSIS
  530.      PROCEDURE GetDOSDateAndTime (VAR JulSec   : REAL;
  531.                                   VAR DateTime : T_DateTime);
  532.  
  533.      VAR
  534.        Seconds     : REAL;
  535.        DOSDateTime : T_DateTime;
  536.  
  537.      BEGIN
  538.        GetDOSDateAndTime (Seconds, DOSDateTime);
  539.        WRITELN ('Today is: ', D2S (DOSDateTime, 'MM/DD/YY');
  540.      END;
  541.  
  542.   DESCRIPTION
  543.      Both the number of seconds from 1840 and the DateTime record are
  544.      returned by this routine.  The DOS values are retrieved using DOS
  545.      calls.  This routine also calls both Date2R and R2Date to update the 
  546.      variables in DateTime (the elapsed time vars). 
  547.  
  548.   SEE ALSO
  549.      Date2R - Date to Real, R2Date - Real to Date, Date2S - Date to String
  550.  
  551.   DEPENDS ON
  552.      Date2R
  553.      R2Date
  554.  
  555.   DIAGNOSTICS
  556.  
  557.   KNOWN RESTRICTIONS
  558.  
  559.   PARTIALLY OBSOLETED BY 
  560.      GetDate, GetTime
  561.  
  562.   UPDATE HISTORY
  563.  
  564.   
  565.  
  566.   NAME
  567. .K:SetDOSDateAndTime - Sets both the DOS date and time
  568.      SetDOSDateAndTime - Sets both the DOS date and time.
  569.  
  570.   SYNOPSIS
  571.      PROCEDURE SetDOSDateAndTime (DateTime : T_DateTime);
  572.  
  573.      VAR
  574.        JS : REAL;
  575.        DT : T_DateTime;
  576.  
  577.      BEGIN
  578.        GetDOSDateAndTime (JS, DT);
  579.        DT.Month := 3;
  580.        DT.Day   := 5;
  581.        DT.Year  := 1986;
  582.        SetDOSDateAndTime (DT);
  583.      END;
  584.  
  585.   DESCRIPTION
  586.      Both the date and time will be reset at the DOS level.  If you only 
  587.      want to reset the date, you should call GetDOSDateAndTime first, 
  588.      otherwise, the time that is set will be random.  Of course, you can 
  589.      set both date and time to the correct values, or you could set the 
  590.      time to zero.
  591.  
  592.   SEE ALSO
  593.      Date2R, R2Date, Date2S, GetDOSDateAndTime
  594.  
  595.   DEPENDS ON
  596.  
  597.   DIAGNOSTICS
  598.  
  599.   KNOWN RESTRICTIONS
  600.  
  601.   PARTIALLY OBSOLETED BY 
  602.      SetDate, SetTime
  603.  
  604.   UPDATE HISTORY
  605.  
  606.  
  607. 
  608.  
  609.